RMarkdown

Quantitative Methodology (UPF)

Jordi Mas Elias

https://www.jordimas.cat/

Sumari

  1. Què és RMarkdown?
  2. Repàs primeres sessions
  3. Tutorial RMarkdown
  4. RMarkdown avançat
  5. Consideracions finals

1. Què és RMarkdown?

Un paquet d’R

S’instal·la com qualsevol altre.

RMarkdown logo.

install.packages(c("rmarkdown", "knitr", 
                   "DT", "vembedr", "leaflet"))

Un llenguatge/prosa

“A Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions”

Illustration of three species of Palmer Archipelago penguins: Chinstrap, Gentoo, and Adelie. Artwork by @allison_horst.

  • John Gruber, 2004.
  • Un format més fàcil de llegir i d’escriure que la majoria de llenguatges web com l’Html.
  • Convertible fàcilment a Html, Pdf…

Eina per a presentar resultats

  • Imprescindible per a un bon analista de dades.
  • Permet transformar en un ampli rang de formats el codi d’R.
  • Exemples:

2. Repàs primeres sessions

RStudio

  • Crear projecte
  • Diferència entre instal·lar i carregar paquets
  • Utilitzar l’Environment
  • Importar arxius: csv, csv2, xlsx, dta, sav…

RMarkdown

Crear un document: YAML - Text - Chunk

RMarkdown logo.

Descarregar tutorial

https://www.jordimas.cat/files/Tutorial_Rmd_Polity.zip

3. Tutorial RMarkdown

Configurar RMarkdown

  • Preview in Viewer Pane
  • Chunk Output in Console
  • Knit: Ctrl + Shift + K
  • Visualització Viewer o Web
  • YAML - Text - Chunk

YAML

  • Què és?
  • Nom, títol i data.
  • ---

Exercici 1: YAML

Provar amb:

output:
  html_document:
    theme: cosmo

Text

  • Negreta, cursives, codi, enllaços, nota al peu1.

  • Seccions i subseccions

  • Ítems i subítems.

  • Ítems enumerats.

Exercici 2: Text

Llegir introducció i fins a la imatge de RMarkdown. Fer els canvis que es proposen en el text.

Chunks

  • Què és? Ctrl + Alt + I
  • Inici i final d’un chunk.
  • Etiquetes del chunk.
  • Elements: echo, eval, message, warning.

Exercici 3: Chunks

Llegir l’apartat chunks i fer canvis que es proposen.

Taules, imatges i gràfics

  • Els posem a dins del chunk.
  • Marc de dades: tibble, kable, datatable.
  • Imatges: ![]() o include_graphics("__").
  • Gràfics: fig.align = "center", fig.width = 50%.

Exercici 4: Dades i gràfics

Llegir l’últim apartat, modifica marc de dades i gràfic.

Avís important

És important diferenciar entre

  • Mode Knit
  • Mode R Script

Activitat

Exercici 5: Polity V

Crear una petita història amb Polity V:

  • Descarregar la base de dades Polity V a Systemic Peace
  • Text amb tots els formats possibles.
  • Un marc de dades i dos plots.

4. RMarkdown avançat I

4.1. RMarkdown avançat (YAML)

Data automàtica

Quan fem Knit, ens imprimeix automàticament el dia d’avui.

date: "`r Sys.Date()`"
[1] "2023-02-23"
date: "`r format(Sys.time(), '%d %B %Y')`"
[1] "23 February 2023"
date: "Última edició `r format(Sys.time(), '%d %B %Y')`"
[1] "Última edició 23 February 2023"

Foto d’encapçalament

Posem una foto a la capçalera del document.

title: "![Posar nom de títol](polity-index.jpeg){width=2in}"

Taula de continguts

Customitzem elements de la taula de continguts.

output:
  html_document:
    toc: true
    toc_depth: 2
    number_sections: true
    toc_float:
      collapsed: false
        smooth_scroll: false

Temes

Seleccionem l’estil visual i el subratllat:

  • Tema: default, cerulean, journal, flatly, darkly, readable, spacelab, united, cosmo, lumen, paper, sandstone, simplex, yeti, null.
theme: paper
  • Highlight: default, tango, pygments, kate, monochrome, espresso, zenburn, haddock, breezedark, textmate, null.
highlight: tango

Plegar codi

Creem un desplegable per cada chunk amb codi (echo = T) que tinguem al document.

title: "Postgrau d'Analista de Dades (UB)"
output:
  html_document:
    code_folding: hide

Formats d’output

Al YAML podem especificar el tipus de format1.

title: "Postgrau d'Analista de Dades (UB)"
author: "Nom de l'estudiant"
output:
  html_document:
    code_folding: hide
  pdf_document:
    toc: yes
  word_document:

I també podem crear diapositives en diversos formats.

4.2. RMarkdown avançat (text)

Canviar mida de text

Un dels deutes pendents de RMarkdown.

    <style>
    body {
    font-size: 13pt;
    text-align: justify}
    </style>

Incloure codi al text

En qualsevol moment podem fer referència al text sobre qualsevol dada ja carregada en un chunk previ.

  • A. Carreguem les dades:
polity <- read_excel("p5v2018.xls")
  • B. Referenciem les dades al text:

En aquest gràfic veiem Estats Units en els darrers anys

p5_ctr <- polity |> 
  filter(country == params$country, year > params$year) |> 
  select(country, year, polity2)
knitr::kable(p5_ctr)
country year polity2
United States 2013 10
United States 2014 10
United States 2015 10
United States 2016 8
United States 2017 8
United States 2018 8

Observem que en l’últim any de dades 2018, United States tenia un nivell de democràcia de 8.

  • r last(p5_dk$year)
  • r params$country
  • r last(p5_dk$polity2)
polity |> 
  group_by(country) |> 
  summarize(duration = max(durable, na.rm = T)) |> 
  ggplot(aes(x = duration)) +
  geom_density()

El règim amb més durada és United States amb 209 anys:

polity$country[which(polity$durable == max(polity$durable, na.rm = T))]

max(polity$durable, na.rm = T)

Referències al text

Per referenciar la secció del document1:

# Introducció {#intro}

En qualsevol moment del text, introduïm:

[text](#intro)

Referències bibliogràfiques

Ho farem normalment amb un document BibTex (.bib)1.

  1. Obrim un Text file, el guardem com a biblio.bib i introduïm:
@misc{Marshall2020,
author = {Marshall, Monty G. and Gurr, Ted Robert},
publisher = {Center for Systemic Peace},
title = {{Polity V. Political Regime Characteristics and Transitions, 1800-2018}},
year = {2020}
}
  1. Indiquem al YAML on es troba l’arxiu:
bibliography: biblio.bib
  1. Citem les referències al text.
  • Entre claudàtors [@Marshall2020], ens posarà (Marshall 2020).
  • Sense claudàtors @Marshall2020, ens posarà Marshall (2020).
  1. En l’última línia del document de RMarkdown, posarem un títol # Referències per separar la bibliografia de la resta del text.

4.3. RMarkdown avançat (chunks)

Taules

Tot tipus de taules amb el paquet KableExtra

polity |> 
  filter(country %in% c("Angola", "Spain", "Vietnam"),
         year == 2014) |> 
  select(country, scode, polity2, durable) |> 
  knitr::kable()

Arguments d’interès:

polity |> 
  select(country, scode, polity2, durable) |> 
  DT::datatable()

Figures

Varis paràmetres per establir les dimensions:

  • fig.width: amplada en inches.
  • fig.height: alçada en inches.
  • fig.align: “left”, “right”, “center”.
  • fig.dim: primer width i després height, c(5,3)
  • out.width: “50%” ocuparà el 50% de l’amplada del report

Opcions globals

Opcions per defecte als chunks de tot el document:

knitr::opts_chunk$set(fig.align = "center", echo = TRUE,
                      warning = FALSE, message = FALSE,
                       fig.width = 6, fig.height = 6)

El primer chunk també és útil per carregar els paquets i objectes que necessitarem.

Què evitar als chunks

  • La funció install.packages().
  • La funció download.file().
  • La funció View().
  • Carregar bases de dades d’internet.
  • Funcions que carreguen bases de dades (ex. CEOdata)

4.4. RMarkdown avançat (publicar)

Exportar i publicar

Tres maneres de publicar en Html:

Activitat

Exercici 7: Prova final

Agafeu el treball d’un dataset anterior i construiu un document Html, procurant d’utilitzar també algunes de les funcions avançades. En particular:

  • Marc de dades en knitr o DT.
  • Temes i subratllats.
  • Plegar codi.
  • Mida gràfics.

Publiqueu-ho a RPubs: A dins d’RStudio, un cop l’Html s’hagi generat en el Viewer, cliqueu a l’icona blava del Viewer (Publish -> Publish a Document), seleccioneu RPubs i seguiu les instruccions.

5. RMarkdown avançat II

5.1. RMarkdown avançat (YAML)

Gràfics per defecte

Els gràfics que apareixen al document han de tenir per defecte algunes dimensions determinades?

title: "Postgrau d'Analista de Dades (UB)"
output:
  html_document:
    fig_width: 6 
    fig_height: 4

Paràmetres

Establim uns paràmetres al YAML que al llarg del document podrem utilitzar com a codi 1.

title: "Postgrau d'Analista de Dades (UB)"
author: "Jordi Mas Elias"
params:
  country: "United States"
  year: 2014

5.2. RMarkdown avançat (text)

Tabsets

## Títol {.tabset}

Aquí comença una tabset.

### Tab A

Contingut de `Tab A`

### Tab B

Contingut de `Tab B`

## {-}

Taules

També una assignatura pendent de RMarkdown.

    | Funció       | Paquet    | Descripció                                           |
    |--------------|-----------|------------------------------------------------------|
    | `filter()`   | `dplyr`   | Filtra les observacions d'un marc de dades           |
    | `separate()` | `tidyr`   | Separa els elements d'un vector en base a un criteri |
    | `read_csv()` | `readr`   | Llegeix els arxius CSV                               |
    | `ggplot()`   | `ggplot2` | Reprodueix elements gràfics                          |
Funció Paquet Descripció
filter() dplyr Filtra les observacions d’un marc de dades
separate() tidyr Separa els elements d’un vector en base a un criteri
read_csv() readr Llegeix els arxius CSV
ggplot() ggplot2 Reprodueix elements gràfics

També podem utilitzar l’Editor Visual (següent).

Editor visual

Interfície més semblant a Word per generar documents.

Amb l’editor visual veurem una interfície que ens serà molt més familiar. No obstant, recomanem utilitzar-lo només puntualment.

Quadres de text

Avís!

Utilitzar quadres de text és una manera efectiva per dirigir l’atenció a determinat contingut.

<div class="alert alert-info">
**Informació!** Blablabla.
</div>

Tipus:

  • primary, secondary, success, danger, warning, info, light, dark.

5.3. RMarkdown avançat (chunk)

Incrustar vídeos i tuits

Amb el paquet vembedr és molt fàcil.

embed_url("https://youtu.be/hz3J6Wb5S_8")

Encara més fàcil amb altres formats de Bookdown:

{{< video https://youtu.be/wo9vZccmqwc >}}
{{< tweet 1229386394658836480 >}}

6. Consideracions finals

Interactius

leaflet() %>% 
  addProviderTiles(providers$Stamen.Toner) %>%
    setView(lng = 139.753930, 
          lat = 35.682170, 
          zoom = 13)

El món de l’endemà

Quarto

Posit

Bibliografia principal

Quantitative Methodology (UPF)